<html>
    <head>
        <title>Swagger 集成</title>
    </head>
    <body>
        <script>
            // Swagger 集成

                   /*
                                Swagger（OpenAPI）是一种与语言无关的规范,用于描述REST API。

                                它允许计算机和人类在不直接访问源代码的情况下了解REST API的功能。

                                其主要目标是：

                                        ①、最小化连接解耦服务所需的工作量。

                                        ②、减少准确记录服务所需的时间。


                                ABP有一个可以通过最少的配置全面实现Swagger的模块，通过使此模块快速集成Swagger。
                   */

                   /*
                        一、安装

                               默认情况下，此软件包已与启动模板一起安装。所以，大多数时候，您不需要手动安装它。

                               如果需要安装，建议使用ABP CLI安装此软件包。


                               1、使用ABP CLI 安装

                                        在 Web 或 HttpApi.Host 项目（. csproj文件）的文件夹中打开命令行窗口，然后键入以下命令：

                                            "abp add-package Volo.Abp.Swashbuckle"

                                        

                                2、手动安装

                                        如果要手动安装：

                                            ①、将 "Volo. Abp.SwashuckleNuGet" 包添加到您的 Web 或 HttpApi.Host项目中：

                                                "Install-Package Volo.Abp.Swashbuckle"

                                            ②、将AbpSwashbuckleModule添加到模块的依赖列表中：

                                                    [DependsOn(
                                                        //...other dependencies
                                                        typeof(AbpSwashbuckleModule) // <-- Add module dependency like that
                                                        )]
                                                    public class YourModule : AbpModule
                                                    {
                                                    }
                   */

                   /*
                        二、配置


                             1、如何配置Swagger

                                        首先，我们需要使用AddAbpSwaggerGen扩展在我们模块的ConfigureServices方法中配置Swagger：


                                                    public override void ConfigureServices(ServiceConfigurationContext context)
                                                    {
                                                        var services = context.Services;

                                                        //... other configurations.

                                                        services.AddAbpSwaggerGen(
                                                            options =>
                                                            {
                                                                options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" });
                                                                options.DocInclusionPredicate((docName, description) => true);
                                                                options.CustomSchemaIds(type => type.FullName);
                                                            }
                                                        );
                                                    }

                            2、使用Swagger中间件

                                            然后我们可以通过调用模块的OnApplicationInitialization方法中的UseAbpSwaggerUI方法来使用Swagger UI：

                                                        public override void OnApplicationInitialization(ApplicationInitializationContext context)
                                                        {
                                                            var app = context.GetApplicationBuilder();

                                                            //... other configurations.

                                                            app.UseStaticFiles();

                                                            app.UseSwagger();  // 使用Swagger中间件

                                                            app.UseAbpSwaggerUI(options =>
                                                            {
                                                                options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API");
                                                            });
                                                            
                                                            //... other configurations.
                                                        }


                                3、 如何在Swagger UI上隐藏ABP端点

                                              如果要隐藏ABP的默认端点，请在Swagger配置中调用HideAbpEndpoints方法，如以下示例所示：

                                                        services.AddAbpSwaggerGen(
                                                            options => 
                                                            {
                                                                //... other options
                                                                
                                                                //Hides ABP Related endpoints on Swagger UI
                                                                options.HideAbpEndpoints();
                                                            }
                                                        )
                   */

                   /*
                        三、将Swagger与OAUTH一起使用

                                  对于非MVC/分层应用程序，我们需要使用OAUTH配置Swagger来处理授权。
                                  
                                  （ABP默认使用OpenIddice。要获取有关OpenIddice的更多信息，请检查此留档。）

                                  为此，我们需要使用AddAbpSwaggerGenWithOAuth扩展来配置带有OAuth颁发者的Swagger，
                                  
                                  并在模块的ConfigureServices方法中配置范围：

                                                 public override void ConfigureServices(ServiceConfigurationContext context)
                                                {
                                                    var services = contex.Services;

                                                    //... other configarations.

                                                    services.AddAbpSwaggerGenWithOAuth(
                                                        "https://localhost:44341",             // authority issuer
                                                        new Dictionary<string, string>         //
                                                        {                                      // scopes
                                                            {"Test", "Test API"}               //
                                                        },                                     //
                                                        options =>
                                                        {
                                                            options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" });
                                                            options.DocInclusionPredicate((docName, description) => true);
                                                            options.CustomSchemaIds(type => type.FullName);
                                                        }
                                                    );
                                                }  
                                                    
                                 然后我们可以通过调用模块的OnApplicationInitialization方法中的UseAbpSwaggerUI方法来使用Swagger UI：

                                        public override void OnApplicationInitialization(ApplicationInitializationContext context)
                                        {
                                            var app = context.GetApplicationBuilder();

                                            //... other configurations.

                                            app.UseAbpSwaggerUI(options =>
                                            {
                                                options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API");

                                                var configuration = context.ServiceProvider.GetRequiredService<IConfiguration>();
                                                options.OAuthClientId("Test_Swagger"); // clientId
                                                options.OAuthClientSecret("1q2w3e*");  // clientSecret
                                            });
                                            
                                            //... other configurations.
                                        }


                                不要忘记设置OAuthClientId和OAuthClientSecret。
                   */

                   /*
                       四、将Swagger与OIDC一起使用

                                您可能还想使用OpenIdConnect而不是OAUTH配置swagger。

                                当您需要配置与颁发者不同的元数据地址时，这尤其有用，例如当您将应用程序部署到kubernetes集群或docker时。

                                在这些情况下，元数据地址将用于登录过程，以通过Internet到达有效的身份验证服务器发现端点，并使用内部网络验证获得的令牌。

                                为此，我们需要使用AddAbpSwaggerGenWithOidc扩展来配置带有OAuth颁发者的Swagger，并在模块的ConfigureServices方法中配置范围：

                                                    context.Services.AddAbpSwaggerGenWithOidc(
                                                    configuration["AuthServer:Authority"],
                                                    scopes: new[] { "SwaggerDemo" },
                                                    // "authorization_code"
                                                    flows: new[] { AbpSwaggerOidcFlows.AuthorizationCode },
                                                    // When deployed on K8s, should be metadata URL of the reachable DNS over internet like https://myauthserver.company.com
                                                    discoveryEndpoint: configuration["AuthServer:Authority"],
                                                    options =>
                                                    {
                                                        options.SwaggerDoc("v1", new OpenApiInfo { Title = "SwaggerDemo API", Version = "v1" });
                                                        options.DocInclusionPredicate((docName, description) => true);
                                                        options.CustomSchemaIds(type => type.FullName);
                                                    });


                                lows是oidc提供程序（Authserver）支持的默认oidc流列表。
                                
                                您可以在下面看到默认支持的流程：

                                            ①、AbpSwaggerOidcFlows.AuthorizationCode："authorization_code"流是默认和建议的流。
                                            
                                                        即使有字段也不需要客户端机密。

                                            ②、AbpSwaggerOidcFlows.Implicit：用于javascript应用程序的已弃用的"implicit"流。


                                            ③、AbpSwaggerOidcFlows.Password：遗留的password流，也称为资源所有者密码流。您需要为其提供用户名、密码和客户端机密。

                                            ④、AbpSwaggerOidcFlows.ClientCredentials：用于服务器到服务器交互的"client_credentials"流。

                                您可以定义一个或多个将在授权模式中显示的流。您可以将其设置为null，这将使用默认的“authorization_code”流。

                                discoveryEndpoint是.well-known/openid-configuration。

                                您可以将其设置为null，这将使用默认的AuthServer：授权应用程序配置。
                                
                                如果您将应用程序部署到kubernetes集群或docker群，您应该将discoveryEndpoint设置为可以通过Internet访问的真实DNS。


                                
                   */


        </script>
    </body>
</html>